ποΈGitΠ―ΡΠ°ποΈ
.specify/extensions/brownfield/README.md 4e48e64e786b58d7c73280f7aa6ebf55be9e53e5 (4e48e64e) Text, 6.13 KB
spec-kit-brownfield
A Spec Kit extension that bootstraps Specification-Driven Development for existing codebases β auto-discover architecture, generate a tailored constitution, and incrementally migrate features into the SDD workflow.
Problem
Spec Kit's T383838specify init creates generic templates that don't fit established projects. Teams with existing codebases face friction adopting SDD:
β’ Generic constitution doesn't reflect actual tech stack, architecture, or conventions
β’ Templates reference placeholder paths instead of real project modules
β’ Multi-module projects (monorepos) get no guidance on code boundaries
β’ No way to bring existing features into the SDD workflow retroactively
β’ Manual constitution creation is tedious and error-prone for large codebases
Solution
The Brownfield Bootstrap extension adds four commands for adopting spec-kit in existing projects:
βββββββββββββββββββββββββββββββββ¬ββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Command β Puβ¦ β Modifies Files? β
βββββββββββββββββββββββββββββββββΌββββββΌβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β T383838/speckit.brownfield.scan β Auβ¦ β No β read-only β
β T383838/speckit.brownfield.bootstrap β Geβ¦ β Yes β creates/updates constitution, templates, AGENTS.md β
β T383838/speckit.brownfield.validate β Veβ¦ β No β read-only β
β T383838/speckit.brownfield.migrate β Inβ¦ β Yes β creates spec.md, plan.md, tasks.md for existing feaβ¦ β
βββββββββββββββββββββββββββββββββ΄ββββββ΄βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Installation
T282828
specify extension add --from https://github.com/Quratulain-bilal/spec-kit-brownfield/archive/refs/tags/v1.0.0.zip
How It Works
Phase 1: Discover
T383838/speckit.brownfield.scan analyzes your codebase to build a project profile:
T282828
Project Profile
βββ Tech Stack: TypeScript (68%), Python (32%)
βββ Frontend: React 18, Vite, TailwindCSS
βββ Backend: FastAPI, SQLAlchemy, PostgreSQL
βββ Architecture: Frontend + Backend (separated)
βββ Modules: client/, server/, shared/
βββ Testing: Jest (frontend), pytest (backend)
βββ CI/CD: GitHub Actions
βββ Branch Pattern: feat/*, fix/*, chore/*
βββ Conventions: kebab-case (frontend), snake_case (backend)
Phase 2: Configure
T383838/speckit.brownfield.bootstrap generates spec-kit configuration from the profile:
β’ Constitution: Rules derived from actual codebase conventions β not generic boilerplate
β’ Spec template: Project-specific sections (e.g., "Database Migrations" for ORM projects)
β’ Plan template: Module-aware implementation phases (e.g., frontend/backend split)
β’ Tasks template: Real test commands and build steps from your actual toolchain
β’ AGENTS.md: Agent boundaries for multi-module projects
Phase 3: Verify
T383838/speckit.brownfield.validate checks that configuration matches reality:
β’ Verifies all directory references actually exist
β’ Confirms mentioned frameworks are in dependency files
β’ Samples files to validate naming convention rules
β’ Detects drift if project has changed since bootstrap
Phase 4: Migrate
T383838/speckit.brownfield.migrate brings existing features into SDD:
β’ Reverse-engineers spec.md from code behavior and test cases
β’ Reconstructs plan.md from actual implementation patterns
β’ Generates tasks.md with all tasks marked complete
β’ Identifies gaps: missing tests, error handling, documentation
Workflow
T282828
specify init β Initialize spec-kit (if not already done)
β
βΌ
/speckit.brownfield.scan β Discover tech stack and architecture
β
βΌ
/speckit.brownfield.bootstrap β Generate tailored configuration
β
βΌ
/speckit.brownfield.validate β Verify configuration accuracy
β
βΌ
/speckit.brownfield.migrate β Bring existing features into SDD
β
βΌ
/speckit.specify β Start new features with project-aware templates
Supported Project Types
ββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Type β Detection β
ββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Monolith β Single source tree, one entry point β
β Monorepo β Workspace config, T383838packages/ or T383838apps/ directories β
β Microservices β Multiple Dockerfiles, service directories β
β Frontend + Backend β Separate T383838client//T383838server/ directories β
β Library/Package β T383838setup.py, T383838lib/ directory, published package config β
ββββββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββββββββββββ
Supported Tech Stacks
ββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Category β Detected β
ββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Languages β TypeScript, JavaScript, Python, Go, Java, Rust, C#, Ruby, PHP β
β Frontend β React, Vue, Angular, Svelte, Next.js, Nuxt β
β Backend β Express, FastAPI, Django, Spring, Rails, Gin, ASP.NET β
β Databases β PostgreSQL, MySQL, MongoDB, SQLite, Redis β
β Package managers β npm, yarn, pnpm, pip, Poetry, Go modules, Cargo, Maven, Gradle β
β CI/CD β GitHub Actions, GitLab CI, CircleCI, Jenkins β
β Testing β Jest, pytest, Go test, JUnit, RSpec, PHPUnit β
ββββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Hooks
The extension registers an optional hook:
β’ after_init: Offers to scan the project after T383838specify init to auto-detect conventions
Design Decisions
β’ Scan before bootstrap β configuration is always derived from actual codebase analysis, never guessed
β’ Confirm before writing β bootstrap and migrate always show a plan and wait for approval
β’ Merge, don't replace β if constitution or templates already exist, merge changes rather than overwriting
β’ Mark migrated specs β reverse-engineered specs include T383838status: migrated to distinguish from fresh specs
β’ Gap reporting β migrate command actively identifies missing tests, error handling, and documentation
β’ Module-aware β all commands understand monorepo and multi-module project structures
Requirements
β’ Spec Kit >= 0.4.0
β’ Git >= 2.0.0
Related
License
MIT
Served by rngit 1.5.2 - Generated in 0.06s